Cartridge Dumping Guide
by Lance Squire and Paul Thacker
version 1.0
Sept. 19, 2010

This guide will allow you to digitally archive Astrocade cartridges using 
VIPERsoft BASIC, a Lil' WHITE RAM expansion, and an AstroBASIC cart.

1)  Loading VIPERsoft BASIC

First,  load VIPERsoft BASIC into your RAM expansion.  This can be done three 
ways:  from a multicart, from a cassette tape, or from a computer.

A multicart is the easiest as you just insert the cart into a running 
Bally/Astrocade. Make sure the expansion switches are properly configured, and 
hit reset.  "VIPERSOFT BASIC" should appear on your screen, and you're good to 
go.

To use a computer, connect a 1/8" mono audio cable (I recommend a gold-plated 
one) from your computer's audio out to the AstroBASIC audio interface.  Make 
sure you can load a BASIC program and adjust volume levels until that works.  
Load VIPERsoft BASIC into the expansion by typing this command into AstroBASIC:

:INPUT%(24576) [GO]

Then play the 2000 baud .wav recording of VIPERsoft BASIC on your computer.

It is also possible to load a 300 baud recording into Bally BASIC though the 
300 baud interface by simply typing:

:INPUT [GO]

If the VIPERSOFT BASIC prompt doesn't appear, type:

CALL 24576 [GO]

This should bring-up VIPERsoft BASIC.

A tape would be a rarity these days. The instructions for loading are the same 
as for a computer, except you need a 'shoebox' tape recorder hooked up instead 
of the computer.

2)  Using the Cartridge Dumping Program

If you loaded VIPERsoft BASIC from a multicart, or into Bally BASIC, then 
switch to the AstroBASIC cartridge, leaving the system running.  VIPERsoft 
BASIC will keep running from the RAM expansion.  Connect a 1/8" mono audio 
cable (I recommend a gold-plated one) from your computer's audio out to the 
AstroBASIC audio interface.  Load the cartridge dumping program by typing:

LOAD [GO]

Then play the .wav recording of the cartridge dumping program on your computer.  
It's a short program and will load very quickly.  Alternatively, you could type 
in the program itself.

10 @(0)=%(!2000) 
20 FOR X=2TO !1FFFSTEP 2 
30 @(X2)=%(X+!2000) 
40 NEXT X 
50 PRINT"IN RAM";INPUT"SAVE ?K(2,4,8)"A
60 GOTO A+100
70 STOP
102 S=!400;GOTO 130 
104 S=!800;GOTO 130 
108 S=!1000 
130 PUT @(0),S;PRINT"SAVED!

Before running the program, gently swap in the cartridge you want to archive, 
again leaving the system running.  Then run the dumping program with:

RUN [GO]

You'll need to wait a minute while the cartridge data is copied into the RAM 
expansion.  When this is finished, the message "IN RAM SAVE ?K(2,4,8)" will 
appear on screen.  Before answering, gently swap back to the AstroBASIC cart, 
and run the audio cable from the audio interface to your computer's microphone 
in.  Open up a sound recording program (such as Audacity) on your computer, 
select microphone for the input, and hit record.

Now, enter 2, 4, or 8 depending on whether you want to save 2K, 4K, or 8K of 
data, and hit [GO].  If you are unsure of the size of the cartridge assume 8K, 
as the extra can be easily removed later.  Wait a minute while the data is 
output.  When the program is finished, it will print "SAVED!"  You can now stop 
recording on your computer.  Then, export the recording as a .wav file.

3)  Processing the Recording into a Binary File

First, you need to convert the .wav file into a .bml file using Ballybin 2.0 
beta.  Open up a command prompt and run the program as follows:

ballybin -v2 -i1 input.wav

-v2 provides verbose output, and -i1 ensures that the data is interpreted as 
binary rather than as BASIC code.  This will output the .bml file, which is an 
XML file containing various information about the recording.

If you open the .bml file in a text editor, you can see that most of the lines 
are formatted like this:

<HEX address=0000>c3 95 21 28 43 29 20 38 31 20 42 41 4c 4c 59 00 <CHAR>..!(C) 
81 BALLY.</CHAR></HEX>

You need to strip out everything in the file except for the hex data, in this 
example:

c3 95 21 28 43 29 20 38 31 20 42 41 4c 4c 59 00

This will be much quicker to do if you can select by column in your text 
editor.  In Word, you can do this with Alt-right-click.  In vi, you can do this 
with Ctrl-v.

Once only the hex data remains, copy it into your clipboard.  Then, open up 
WinHex, available as a free demo from:

http://x-ways.net/winhex/

In WinHex, select "Edit / Clipboard Data / Paste Into New File".  Select "ASCII 
Hex" as the clipboard format.  With the data loaded, look on the left column to 
confirm that the file size is correct (2K, 4K, or 8K).  Finally, select "File / 
Save As..." and save the data into a .bin file.

You're finished!  You can load the .bin file into an Astrocade emulator, or 
burn it onto a ROM and play it on your system. 
